COMMENT ⊗   VALID 00013 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	The MAIL program
C00013 00003	Destination lists
C00022 00004	Message and message file formats
C00029 00005	Command switches
C00037 00006	Dates and times
C00045 00007	Mail to other ARPA network hosts
C00056 00008	Special MAIL commands: EVENT, PLAN, RETRY
C00061 00009	Delayed program execution: LATER and BATCH
C00071 00010	The REENTER error recovery facility
C00076 00011	Hand-holding mode
C00078 00012	Interfacing to MAIL from other programs
C00087 00013	Summary of major differences from the old MAIL program
C00090 ENDMK
C⊗;
The MAIL program

The MAIL program is used to send messages to users and sometimes
to arbitrary disk files for special purposes.  The program is
invoked by one of several monitor commands, depending on the
function desired:

SEND	send a message to the terminal of one or more currently active users
MAIL	send a message to files to be read later by one or more users
GRIPE	send a message about system problems to a file read by system programmers
PLAN	create a file describing how to find you when not logged in
EVENT	send a message to all users about an event on a particular date
REMIND	schedule a message to be sent at some later time
LATER	schedule the execution of an arbitrary program at some later time
BATCH	schedule the execution of a command string at some later time

The commands SEND, MAIL, and GRIPE may be given when not logged in, so
that people who are not authorized users of our system can use them to
communicate with us.  However, users who are not logged in may not use
wildcard (send to all users) or ARPA network destinations.  A user who
is not logged in will be asked for his name, which will be included in
the header of the message.

Most of these commands require, as arguments, a list of recipients or
destinations and the text of the message.  Some commands take extra
arguments, such as a date and time for the REMIND command.  Several
options can be selected by switches in the command string, applied
either globally or to a particular destination.

The normal command syntax includes all necessary information on one or
more lines without prompting.  There is an alternative format, hereafter
called "hand-holding mode", in which each piece of information required
is prompted for separately.  The latter syntax is much more verbose and
time-consuming to use, but may be less confusing to new users.  It will
be described in a separate section; what follows here assumes that the
normal syntax is being used.

Before explaining the complete range of command options, here are
a few sample commands:

SEND BH Want to have dinner?

	This is a very simple example of a command with one destination
	and no option switches.  It types the message "Want to have dinner?"
	on BH's terminal if he is logged in, along with a header indicating
	who sent the message.  If BH is not logged in, MAIL asks if the
	message should be mailed instead of sent.

MAIL/DIST @NL Language group meeting Tuesday at 3pm.

	This command mails the message ("Language group ...") to the
	mail files of the users listed in the file NL.DIS or NL or
	NL.DIS[P,DOC] (the [P,DOC] file directory contains lists of
	users by project group).  The first file in that list which
	exists is used.  The message will include the standard header
	indicating who sent the message and when, and also (because
	of the /DIST switch) a line indicating to whom the message
	is being sent.

REMIND/DATE=10-*-* . Rent due tomorrow

	This command reminds the user who isssued the command (becuase
	of the "." destination) to pay the rent on the tenth day of
	each month.  The reminder is both sent and mailed each time,
	and expires after 50 times.  (These are default conditions
	modifiable by switches.)

The basic command format for all MAIL commands is

<command> <destinations> <message>

which can be complicated by switches applied to the entire command or
to an individual destination.  The message text can be provided in
any of three ways: if no message specification is given on the
command line (or the same line as the last destination for a
multi-line command), MAIL asks for a message to be entered from the
terminal, ending with the end-of-file character (<control><meta><lf>
from a Stanford display terminal, <control>Z otherwise).  If the
notation "@file.ext[prj,prg]" is used on the command line after the
last destination, the message text is taken from the specified file.
(If no extension is typed, the file FILE.TXT is tried first, and
then FILE with no extension.  To force the use of FILE with no
extension, type "@FILE.".)  The file may contain an E directory
or SOS line numbers, which will not be included in the message.
If something not starting with "@" follows the destination list on
the command line, it is taken as the message text.  This makes
single-line messages more convenient to enter.  If you start to
enter a single-line message, and decide you need more than one line
after all, end the command line with <lf> instead of <cr> and you
will be allowed to continue the message on later lines.

When entering a message from a Stanford display terminal, the usual
line editing facilities are available.  Two additional provisions
are made for editing the message text: if the <bs> key is typed
when the line editor buffer is empty (i.e., at the beginning of a
new line), the last line typed is loaded into the line editor and
the cursor is positioned at the end of that line.  The text of that
line is deleted from the accumulated message.  The effect is that
a line break can be deleted by <bs> like an ordinary character.
It is possible to back up more than one line by typing, e.g.,
<bs><clear><bs>, but this procedure destroys the lines after the one
to which you back up, and the backup is only possible for a small
(about 30) number of lines.  A better facility for correcting
errors more than one line before the current line is that typing
<control><meta>E while typing the message text will write the
MAIL command, switches, and destination list on page 1, and the
message text on page 2, of a file called MAIL.TXT in your login
(not alias) directory and then automatically run E to allow you
to edit the text.  (E will start up pointing at the second page
of the file, but you can also modify the command or destinations
by editing the first page.)  Type the E command <control>XRUN
to restart the MAIL program and send the message as edited.
The MAIL.TXT file is automatically deleted after sending the message.

The character <altmode> may not appear in a message (because it is a
line editor activator and would confuse some mail-reading programs).
If an altmode is seen in the message text as input, it is changed into
a dollar sign ($).

If the /SUBJECT switch is used to include a subject line in the
message header, the subject is taken from the first text line
entered: for a file, the first line of the file is the subject;
what would otherwise be a single-line message is taken as the
subject line for a multi-line message to follow.  If no message
is provided on the command line, you are prompted for a subject
line and then for the message text.
Destination lists

The commands SEND, MAIL, and REMIND require one or more recipients,
or destinations, specified in a list.  The destinations should be
separated by commas.  The list may extend over more than one line
if the lines before the last end with comma.  (Any characters from
a semicolon to the following linefeed are ignored.)  The following
types of destinations may be used:

PRG		programmer name of local user
name		real name (or leading substring) of local user
name % host	user at another ARPA network host
% host		"sticky" ARPA network host to be used for following names
*		notice for all users
[PRJ,PRG]	PPN of local user (mail to PRG is more commonly used)
[PRJ,*]		notice for all users in a project group
#fil.ext[pj,pg]	(MAIL only) arbitrary file to receive message
TTYn		(SEND only) terminal to receive message
n		(SEND only) job number to receive message
@fil.ext[pj,pg]	file containing destination list

PRJ and PRG in the above list must be one to three letters and digits,
or the character "." for your own login PRJ or PRJ, or the character
"*" for wildcard PRJ or PRG.  (For example, "[*,PRG]" is equivalent
to "PRG".)  In the case of PRG without brackets, the first character
must be a letter.  Upper and lower case letters are equivalent.  In
the formats listed as "name" above, the name must consist of any number
of letters, digits, and hyphens, or of arbitrary characters enclosed
in quotation marks ("...") or downarrows (↓...↓).  In the SEND command,
the TTYn form may optionally be followed by a colon.  The SEND command
also allows a special destination of the form "ARPA" or "ARPA*" which
sends to all users logged in via the ARPA network.

ARPA network hosts are specified by host name (1 to 12 letters, digits,
and hyphens starting with a letter) or by decimal host number.  If the
host name is used it can be abbreviated by enough characters to identify
it uniquely.  Many hosts have short "nicknames" recognized by the
network programs at Stanford.  Mail will only be sent to a host
specified by name if the host is listed in our host table as a server
(that is, a host which accepts incoming connections).

A host may be specified for a single destination, using the "name%host"
notation, or a "sticky" host may be specified by just "%host" which will
apply to all following destinations starting with a letter or a quote
character until another sticky host is specified.  (Note that bracketed
PPN, "*", and job number destinations are not affected by a sticky host
but that PRG and TTYn are affected.)  A host name of SU-AI (or SAIL)
will override a sticky host but will not actually send the message
via the ARPA network.

There is no ARPA network standard protocol for implementing the SEND
command to a remote host.  However, a private protocol for this purpose
has been implemented for use between SAIL and the ITS systems at MIT.
The MAIL program will attempt to use this protocol to any host, but it
isn't going to work except to an ITS.  In particular, the designers of
TENEX object to SEND on principle, because they don't know display
terminals have been invented yet.

More information about ARPA network mail will be given later.

The #file construction, if no extension is typed, uses a default
extension of MSG.  To mail to a file with no extension, you must
type the filename in the form "#file." with no extension after the dot.

The @file construction, if no extension is typed, uses a default
extension of DIS (distribution list).  FILE.DIS is looked for first,
then FILE (both on your current alias directory), then FILE.DIS[P,DOC].
The [P,DOC] directory contains several distribution lists derived from
the laboratory personnel directory.  For example,

SEND @VB Time for volleyball!

will send that message to all known volleyball players as listed in
the file VB.DIS[P,DOC] (see LES to be added to the list).  Distribution
list files may contain E directories or SOS line numbers.  Only the
first page (second page if in E format) is read.  Everything on that
page will be interpreted as destinations even if not properly separated
by commas.  (The semicolon format for comments will work.)

For the MAIL command, if there is a file called OUTGO.MSG in your
login (not alias) directory, it is automatically included as a
destination for the message.  If the destination list includes
"#OUTGO" the message will be sent to that file twice!

Messages can only be sent to local users who have file directories.
The check for validity of PPN recipients is made as soon as the
destination list is read.  If some but not all of the destinations
are valid, MAIL asks whether or not to proceed using the valid ones.
It is possible to recover a destination list and message to correct
errors by using the monitor REENTER command, as explained later.

For the SEND command with a multi-line message (so the destination
list is read before the message has been entered), a warning message
is typed if any PPN recipient is not logged in.  This warning does
not require reconfirmation before the command is executed.

For people who want to send mail to a list of people designed for use
by SNDMSG at a TENEX site, which requires a different syntax, the /ARPA
switch can be used to parse destination files differently, including
the use of "@" to indicate a network host name.  Obviously nesting of
distribution files is not possible within such a file.  See the description
of the /ARPA switch below for more details.
Message and message file formats

A message sent to a logged-in user's terminal by the SEND command is
preceded by a header line of the form

;; Message from PRJ,PRG at TTYn  hhmm	subject

containing the sender's PPN and TTY, the 24-hour time of sending,
and the subject of the message if one was specified by the sender.
This may optionally be followed by one or more lines listing the
recipients of the message, who may be divided into "primary" and
"secondary" recipients; the former will be listed on lines starting
"To: " and the latter on lines starting "CC: ".  Then the text of
the message is sent.

Normally, if a distribution list file was used to specify the
recipients of the message, the optional list of recipients included
with the message will contain only the name of that file, not the
actual recipients listed in it, to avoid very long recipient lists.
The /LIST switch (see the section on switches below) will include
the recipients given in the file in the list in the message.

The header line may have some additional information in special cases.
If the message was sent to all users by a SEND * command, the header
line starts ";; Message to * from".  If the sender is not logged in,
his PPN is 100,100 and he is asked to supply his real name, which is
included in the header.  If the sender is logged in from another ARPA
network host, the host name is also included in the header.

The header line for mail sent to a local file has a somewhat different
format:

∂dd-mon-yy  hhmm	PRJ,PRG		subject

The other lines are the same as in the SEND format.  The header is
preceded by a formfeed character.  Extra information may be included
as in the SEND format.

In both SEND and MAIL formats, the PPN of the sender will be in the
form PRJ/PRG instead of PRJ,PRG if the message is a reminder.

The default option is to include the distribution list lines in mail
sent to other hosts on the ARPA network but not to include them in
messages sent or mailed locally.  The switch /DIST includes the list
in local messages, and the /NODIST switch eliminates it from ARPA
network messages.  Note that these switches are not inverses, and that
/-DIST and /-NODIST exist as for other switches!

When mail is sent to a file which already exists, the beginning of
the file is read to see if it contains an E directory.  If so, the
message is added at the end of the file.  The directory is not
updated to reflect this new page, but the formfeed will be at a
record boundary, so when the file is next edited with E, the
directory can be updated without reformatting the file.  If the
file does not already contain an E directory, the message is added
at the beginning of the file.  In this case, record boundaries are
not necessarily preserved, but word boundaries are.  The /APPEND
switch will cause the message to be added at the end of the file as
if there had been a directory.

When a message is sent to a file which did not formerly exist, the
switches /E and /-E can be used to control whether or not a directory
is created for the new file.  The default is an assembly parameter
of the MAIL program.  It has initially been set to /-E so that the
new MAIL program will be compatible with old mail reading programs,
but it is intended that E eventually take over the functions of
reading mail and that /E become the default.

Mail sent over the ARPA network is preceded by a header in more or
less the standard format, consisting of several lines of the form
"Keyword: data" (date, from, to,...).  We use a nonstandard format
for the "from" line, which contains the sender's real human name
as well as his network mailbox, in the form

From: Brian Harvey (BH @ SU-AI)

The MSG program on TENEX, which uses the from line to provide an
automatic reply feature, knows about this format and handles it
correctly.  There is a new mail header standard in the works, which
calls for lots of useless garbage like a supposedly-guaranteed-unique
message ID line to help the bureaucrats or the CIA or someone like
that keep track of the message; we don't supply that.
Command switches

Several switches can be specified in the command line to modify
the operation of the MAIL program.  Some may be used only globally,
just after the command name, while others can be applied either
globally or to a particular destination.  Switches may be used at
the beginning of a distribution list file, in which case they
apply globally to all destinations within that file.  Most switches
are available in positive and negative senses (/FOO and /-FOO);
a switch specified for a particular destination generally overrides
a global switch.  Switches specified with the @file destination
format override file-global switches at the beginning of the file.
Switch names may be abbreviated by enough characters to identify
the switch uniquely.  Here are the available switches:

switch	/-switch OK for		meaning
name	exists?  dest?

EXPAND	yes	yes*	(REMIND only) expand the distribution list file
			now instead of when the reminder is actually
			sent.  *-This switch may only be used on destinations
			of the form @file, and applies only to the file
			itself (not to any @file destinations within the
			file).  If given globally or file-globally,
			however, it propagates downward.  /-EXPAND implies /-LIST.

NOMAIL	yes	yes	(SEND only) Do not mail the message to a destination
			PPN if the user is not logged in.

YESMAIL	yes	yes	(SEND only) Do mail the message to a destination
			PPN if the user is not logged in.

MAIL	yes	yes	(SEND only) Mail the message to a destination
			PPN as well as sending even if the user is logged in.
			(Note that this switch has a different meaning
			for the REMIND command.)

SUBJECT	yes	no	Include a subject line in the message.

WHERE	yes	yes	(SEND or MAIL) Type the WHO line for any PPN
			destinations if the user is logged in.

DIST	yes	yes	Include the list of destinations in the text
			of the message for local recipients (see header format).
			Compare /NODIST below.

CC	no	yes	List this destination and all after it as secondary
			(CC) recipients (see header format).  This switch
			does not imply /DIST.

APPEND	yes	yes	(MAIL only) Put the message at the end of the file
			instead of the beginning even if it has no directory.

QUEUE	yes	yes	Queue ARPA network mail for later delivery without
			first trying to send it immediately.

SEND	yes	yes	(REMIND only) Do not mail the reminder to the
			destination PPN when the time comes, send only.

MAIL	yes	yes	(REMIND only) Do not send the reminder to the
			destination PPN when the time comes, mail only.
			(Note that this switch has a different meaning
			for the SEND command.)

LIST	yes	yes	List the destinations specified within a
			distribution list file as well as the file
			itself.  For REMIND, /LIST implies /EXPAND.

NODIST	yes	yes	Do not include the list of destinations in the text
			of the message for ARPA net recipients (see header format).
			Not the inverse of /DIST!

HEADER	yes*	yes	Include the header line in the mailed message.
			*-Unlike most switches, this defaults to on!

NO	yes	yes	This is equivalent to /NOMAIL for the SEND command
			and to /NODIST for the MAIL command, so that /N
			can be used to abbreviate the appropriate switch.

E	yes*	yes	Include an E directory if creating a new message
			file.  *-The default value of this switch is
			an assembly parameter of the MAIL program and
			is currently /-E.

DATE	no	no	(REMIND only)  This switch is used in the form
			/DATE=<date> and sets the delivery date for a reminder.
			See the dates and times section.

TIME	no	no	(REMIND only)  This switch is used in the form
			/TIME=<time> and sets the delivery time for a reminder.
			See the dates and times section.  If /DATE and /TIME
			are both used, /DATE must come first.

COUNT	no	no	(REMIND only)  This switch is used in the form
			/COUNT=<number> and sets the expiration count for a
			reminder.  See the dates and times section.

ARPA	no	yes*	*-This switch may only be used with a destination of
			the form @file or as a file-global switch in such
			a distribution list file.  It changes the syntax
			of the destination processor so that the character
			"@" precedes an ARPA network host name instead of
			a distribution list file name, and all SIXBIT
			characters except space, comma, colon, quote ("), and
			at (@) are allowed in names without using quotes.
			A name ending with a colon (distribution list name
			for SNDMSG) is ignored. The switch is intended for
			files from systems like TENEX with less sophisticated
			mail programs.
Dates and times

The REMIND command allows the delivery of a message to be delayed until
a particular date and time, and to be repeated periodically.  (The most
frequent repetition provided is once daily.)  There are two ways to
provide the date and time information to REMIND.  The less confusing
is to use the switches /DATE=date and/or /TIME=time (if both are used,
/DATE must precede /TIME) after the REMIND command name.  These
switches may only be used globally.  If neither switch is used, the
MAIL program will expect a date and/or time after the destination list
and before the message text.  Dates can be in any of the following
formats:

	4/28/75		28-APR-75	APR 28, 75
	4/28/1975	28-APR-1975	APR 28, 1975
	4/28		28-APR		APR 28
	4/28/*		28-APR-*	APR 28, *
	*/28		28-*		+3
	WED		WED*		W		W*

Visitors from Europe please note that the slash format is
month/day/year, not day/month/year!  "*" can be used in place of
the month for a reminder to be repeated monthly, or in place of
the year for a yearly reminder.  If "*" is used for the month but
not for the year, the reminder expires at the end of the specfied
year, or the current calendar year if none is specified.  If a
specific month and date are given but no year, either the current
year or the next year is used, depending on whether the date has
already passed in the current year.  (Today's date is considered
as already passed for this purpose.)  Months and days of the week
may be indicated by as many letters as are required to identify the
name uniquely.  For days of the week, the one-letter abbreviations
M T W R F S D are provided.  A day of the week followed by "*"
represents a reminder to be repeated weekly.  The "+3" format is
used to indicate a reminder to be sent once, 3 days from today.
If a time but no date is given, today's date is used unless the
given time has already passed, in which case tomorrow's date is
used; however, if no date is given, the time specification may
be followed by "*" for a reminder to be repeated daily.

Times may be in any of the following formats:

	1423		223pm		223p
	14:23		2:23pm		2:23p
	0223		223am		223a		223
	02:23		2:23am		2:23a		2:23
	2		2am		2pm		2a
	+2:23		+2:		+:23		2p

Times with three or four digits and no colon normally imply AM if
less than 1200 and PM otherwise (the allowable range is 0000-2359);
it is possible to specify AM or PM explicitly, however, if the
number is in the range 0100-1259.  If no explicit date is given
in the command, times with one or two digits, or
with a colon, and in the 1:00-12:59 range will normally be the
nearest such 12-hour time which has not yet passed, which might be
this morning, this afternoon, or tomorrow morning.  An explicit AM
or PM may be given to change this default assumption.  If a date
is given as well as a time, times in the 0:00-11:59 range will
normally be considered AM and 12:00-23:59 will be considered PM
as for the four-digit times.  Note: if an explicit AM or PM is
given, it must follow the time number with no intervening spaces!
This requirement is necessary to distinguish the AM or PM from the
possible beginning of the message text or of a destination name.
Note 2: a time of 12:00AM is midnight, and 12:00PM is noon.  The
mnemonic is that 12:00 is a minute before 12:01.

If no explicit time is given, the default is midnight of the given
date.  (That is, the midnight at the beginning of that date.)  The
relative time forms may only be used if no date is explicitly given,
and must contain a colon so that +2 days can be distinguished from
+2: hours.

Reminders which are to be sent more than once must also have an
expiration count; if none is specified by the user, a default
count of 50 is supplied.  The count can be given with a /COUNT=n
global switch or by #n after the date and time if the alternate
notation is used.  (The "#" is not used for the switch format.)
A count of 0 or ∞ will prevent the reminder from expiring unless
it is explicitly cancelled by the user.

Reminders are normally both sent and mailed at the specified date and
time.  The switches /MAIL or /SEND can be used for mail-only or
send-only reminders; however, if a repeated reminder is being sent
for the last time because its expiration count has run out, it is
always mailed even if /SEND was used in the command.  A warning that
the reminder has expired is included in the text of the message in
this case.
Mail to other ARPA network hosts

Mail can be sent to users of other computer systems connected to the
ARPA network.  To send network mail, you must tell the MAIL program
the name of the recipient as understood by the other host, and the
name of the host.  Each host has an official name, a string of letters,
digits, and hyphens.  For example, our host name is "SU-AI".  Hosts
may also have unofficial "nicknames"; we assign a short name to every
host on the network.  Either the official name or the nickname can be
used to identify a host; you need only type enough characters to
identify the host uniquely.  For example, we have the nickname "SAIL"
which can (as of this writing) be abbreviated "SA".  Each host also
has a number; you can type a decimal host number instead of a name.
The format for a network destination is

	name % host

where "name" is the recipient's name at the host and "host" is the
host name or number.  The recipient name can contain upper and lower
case letters, digits, and hyphens; if any other characters are
required the name must be enclosed in quotation marks ("...") or
downarrows (↓...↓).  The name must also be quoted if it does not
start with a letter.  Some hosts may consider the case of letters
significant in their user names.

To send a message to several users at the same host, it is possible
to specify a "sticky" host with a pseudo-destination of the form

	% host

Thus, the command

	MAIL FEINLER%BBNB,%AI KLH,TK,MINSKY,BH%SAIL,PAPERT

will mail the message to these recipients:

	FEINLER at host BBN-TENEXB
	KLH at host MIT-AI
	TK at host MIT-AI
	MINSKY at host MIT-AI
	BH at host SU-AI
	PAPERT at host MIT-AI

(Of course, mail to SU-AI is not actually sent via the ARPA network!)
The sticky host specifier ("%AI") was not followed by a comma in the
example above; the comma is optional following sticky hosts since the
use of a sticky host implies that at least one destination will
follow.

Not all network hosts are servers; that is, some hosts can originate
network connections but do not accept connections originated from
another host.  Mail can only be sent to servers, and the MAIL program
will refuse to try to mail to a host which is not known to be a
server.  We are supposed to be notified promptly of host status
changes, so our host tables should be up to date most of the time, but
if MAIL does not recognize a host you think it should, consult a
system programmer.  MAIL will always accept hosts specified by number.

Note that a sticky host applies only to destinations which are
recognized as names, i.e., quoted or starting with a letter.  Thus

	MAIL %AI [1,BH],HQM

mails to [1,BH] at Stanford and to HQM at MIT-AI.

Network mail may not be delivered successfully on the first try,
because the other host or the network communications equipment
may be down.  Therefore, the result of a network mail attempt is
reported with one of three messages:

	USER at HOST -- ok
	USER at HOST -- refused
	USER at HOST -- queued

The first message means that the mail was sent and acknowledged by
the other host.  The second means that the network connection was
established but the other host rejected the mail, for example, because
it did not recognize the recipient as a user of that system.  Usually
the other host will send back a message explaining why the mail was
refused, which the MAIL program types out.  The third message means
that the network connection could not be made or was interrupted.
The message is queued like a reminder and is automatically retried
at three-hour intervals for three days.  (The first repeat attempt
is made 15 minutes after the original failure.)  You can use the
RETRY command (see the section on special MAIL commands) to retry
your queued mail manually.  You will be notified via SEND and MAIL
of the eventual disposition of queued mail; the possibilities are

	Mail to USER at HOST -- ok
	Mail to USER at HOST -- refused
	Mail to USER at HOST -- expired

The last of these means that the three-day limit ran out without
a successful connection.

When a message which was typed in from the terminal (not read from
a file) is queued, the message text is also written in a file named
FAILED.TXT in your login directory.  This file is not necessary for
the operation of the queuing system, but can be used if you want to
redirect the message.  (For example, you might know that the recipient
is also accessible through another host.)

The header format for network mail is different from that used for
local mail.  The section of this document on header formats explains
the network header.  In particular, the distribution list (list of
recipients of the message) is by default included in network mail
but not local mail.  The /NODIST switch will eliminate the list
from network mail.

If you often communicate with users at other hosts, you may want to
send mail to a group of people listed in a file which was prepared
elsewhere.  To make this easier, the switch /ARPA applied to a
distribution-file destination causes the file to be scanned using
the syntax of the SNDMSG program on TENEX systems.  Specifically:

	The character "@" is used instead of "%" to indicate
	network host names.

	Any character may be used in a recipient name except
	space, return, linefeed, tab, quote, colon, comma, and
	atsign without quoting the name.  Note in particular that
	semicolon is a valid recipient name character.

	A recipient name ending with colon (distribution list name)
	is ignored completely.

If you are sending mail to several users at other hosts, it can be
very time-consuming to wait for all the network connections to be
made.  The /QUEUE switch can be used either globally or for individual
recipients to tell MAIL to queue the message immediately, without
trying to send it.  In this case, the first attempt will be made
essentially immediately instead of 15 minutes later, but the attempt
will be asynchronous with your own job.  Note: during busy hours there
may be no job slot available for the remind phantom, in which case the
mail will not be sent immediately if /QUEUE is used.

There is no ARPA network standard protocol for implementing the SEND
command to a remote host.  However, a private protocol for this purpose
has been implemented for use between SAIL and the ITS systems at MIT.
The MAIL program will attempt to use this protocol to any host, but it
isn't going to work except to an ITS.
Special MAIL commands: EVENT, PLAN, RETRY

Notices to all users (MAIL *) may only be relevant for a short time.
Therefore, a facility is provided to associate an "expiration date"
with such a notice.  To do this, use the /DATE switch as in the
REMIND command.  The date must not be "wild", i.e., one specific
date must be determined by the switch.  The notice will expire at
midnight at the start of the given date; therefore, the notice will
last be seen on the previous day.  The /DATE switch may be used for
messages other than MAIL * but will not have the effect of deleting
the message.  This expiration facility is implemented by including
the expiration date (the date's DAYCNT number in octal) in the
message header.  A program run every midnight deletes expired notices.

For notifying users of an event on a particular day, a more useful
facility is to repeat the notice the day before the event and the
day of the event.  The EVENT command does this, by including more
than one expiration date in the message header.  The command
syntax is

	EVENT date message

where "message" can be in any of the usual forms.  The EVENT command
implies MAIL *.  The date should not be given as a switch for this
command.  The date must be at least the day after the command is given.

The text of the notice produced by the EVENT starts with a line of
the form

	Event of dd-mon-yy

immediately after the header line, so the date need not be included
in the text you type in.  (The time of the event should, of course,
be included in the text.)

The event notice will be deleted and re-entered in the notice file
(so that users will see it again) the day before the event and the
day of the event.  It is finally deleted the day after the event.
(Remember, the deletion of expired notices happens at the beginning
of the day!)  If the event is on a Monday, the notice is deleted
and re-entered on the preceding Friday as well as the other days
mentioned above.

The PLAN command is used to create a file describing your whereabouts,
office schedule, or whatever, to be read by users who give the FINGER
command to find you when you are not logged in.  This command is like
MAIL #∂.PLN except that the message you give replaces the previous
contents of the file instead of being added to the file.  If you enter
a null plan (PLAN <return> <end-of-file>) your plan file is deleted.
The plan applies to your login programmer name.

The /DATE switch can be used (and is recommended!) to set an expiration
date for your plan.  This is implemented by entering a LATER request
(see next section) to delete the plan file.  /DATE is the only switch
allowed with the PLAN command.

The RETRY command is used to retry all queued mail immediately.  It
searches the reminder queue for queued mail (not reminders) sent by
your login programmer name and tries to send the mail.  (This will
be done automatically without using the command, but the command is
provided for impatient mailers.)  Please do not type <call> after
giving this command, or you may lose a queued message.
Delayed program execution: LATER and BATCH

The REMIND command, in essence, allows the execution of a SEND or
MAIL command to be delayed to a specified time.  This delayed
execution is generalized to allow an arbitrary program to be run,
or an arbitrary sequence of commands to be carried out, at a
later time.  The two commands for this purpose are LATER and BATCH.

The LATER command schedules delayed running of a specified program
dump file.  The command format is

	LATER dumpfile core datetime count

The defaults for the program file to be executed are device DSK,
extension .DMP, and your alias PPN.  If a device is explicitly
specified, it must be DSK or SYS.  No check is made when the command
is given to ensure that the specified file exists or is a valid
program dump file.

The optional core argument can be used to control the core size and
starting address used to run the program.  If this argument is not
used, the program will be given as much core as is needed to fit it,
and will be started at its normal starting address.  The core argument
can be in any of these formats:

	<nK>	<+m>	<-m>	<nK,+m>	<nK,-m>	<+m,nK>	<-m,nK>

(The angle brackets are actually to be typed.)  The nK subargument
specifies the number of 1024-word blocks of core to be assigned to
the program; n is a decimal integer.  The +m or -m subargument is
a starting address offset, that is, m will be added to or subtracted
from the program's normal start address.  Note: m is an OCTAL integer.

The date and/or time must be given, in the same format as for the
REMIND command.  The optional count argument, as in the REMIND
command, is given in the form #n (#0 or #∞ for infinite count).
This command does not accept switches; the non-switch syntax
must be used for date, time, and count.

The LATER command requires all its arguments on the command line.
If the proper syntax is not followed, a message is typed explaining
the proper syntax and nothing else is done.

When the job is run, it will have your login PPN as its login and
alias PPN.  It will have no privileges, including the Local User
Privilege; this means it will be restricted somewhat about file
access.  Also, it is run as a phantom job: if it is stopped because
of an error, the job is killed.

Certain registers are set up when the program is started to
communicate information from the remind phantom to your program:

	register	contents

	1		filename of program dump file
			  (same as job's name)
	2		extension of program dump file
	3		PPN of dump file ([1,3] if SYS: was specified)
			  (not necessarily the job's login PPN)
	4		-1 if this LATER request will not be run again
			  otherwise 0

The BATCH command (below) uses this information to delete the dump
file when the command is run for the last time.

The program can only be run if a job slot is available at the time
for which it is scheduled.  If the remind phantom is unable to run
the program because no job slots are available, it does not try
again later (unless, of course, the date-time specifies repetition).
If the system is so crowded that job slots are in short supply, users
who are present in the flesh get priority over LATER requests.  This
is rarely a problem except for weekday afternoons.  (If there is no
job slot for the remind phantom itself, it will try to run your request
once, as soon as it is run itself.)

Often, what you want to delay is the execution of one or more monitor
commands, rather than just a single program.  To allow this, the
BATCH command accepts a command string and enters a LATER request
to run a program which enters the commands through a pseudo-teletype.
The format is like that of the REMIND command, except that the only
relevant switches are /DATE, /TIME, and /COUNT.  The "message" is
a command or sequence of commands.  A special switch, /DO, causes
certain character conversion to be done when entering the commands,
as in the DO program:

	character	effect

	RETURN		ignored
	LINE		ignored
	↔		translated to RETURN
			  (the monitor supplies an automatic LINE)
	↓		translated to LINE
	≠		translated to ALT
	β		translated to deferred CALL
	VT		adds CONTROL bit to following character
	λ		adds CONTROL bit to following character
	FORM		adds META bit to following character
	α		adds META bit to following character
	⊗		translated to ESC
	⊗-		translated to BREAK
	≡		quote the following character (no translation)

Note that the characters | and ? which have special meanings in the
DO program are not treated specially by the BATCH/DO command.

The BATCH command can be used to run a command file through a
pseudo-teletype immediately by using the /NOW switch and not
giving a date or time.  Otherwise, the command must include a
date and/or time, as for REMIND.

If the /NOW switch is used in the BATCH command, BATCH executes the
desired commands immediately.  Otherwise, it writes a file on your
alias directory called BATn.DMP (n is a number chosen to make the
name unique) and enters a LATER request for the running of that file.
The BATn program types the desired commands into a pseudo-teletype
when it is run.  The LATER request starts the BATn program at one
more than its normal start address; if it is started normally, it
types out the commands stored in it, so you can find out which
BATCH program is which if you enter more than one.  When the BATn
program is started by the LATER request, it writes a file called
BATn.LOG in your login directory with a log of the commands and
typed output.  (If BATCH runs the commands immediately, the log
file is called BATCH.LOG and is written in your alias directory.)

The BATn.DMP file is deleted when the request is being run for the
last time.

The BATCH command has many deficiencies when considered as a full
batch processing facility.  There is no way to control the commands
issued on the basis of past output, no provision for aborting a
command sequence if an error occurs, no provision for mounting tapes
or collecting listings.  The command is not intended as a real batch
processing system, but merely as a convenience for delaying the
execution of simple commands.
The REENTER error recovery facility

The MAIL program remembers all of its input after execution, and can
be made to repeat the command with modifications to the command,
switches, destinations, and message.  To invoke this facility, type
REENTER to the monitor.  (To use this feature while typing in the
message text, you can type <call> and REENTER, but any text still in
the line editor buffer or the TTY buffer when you type <call> will
be lost.  Unless the system is very heavily loaded, the problem of
losing text from the TTY buffer should not come up, but be sure to
type <cr> to activate any text in the line editor before typing <call>.)

Two different modes of REENTER operation are provided.  If the command
and destination list were all typed on one line of input from a Stanford
display terminal, that line is loaded into the terminal's line editor and
can be edited and re-activated.  In this case, the program forgets all
about the previous command and starts from scratch when the edited
command is seen.  The text of a single-line message will be included
in the reloaded line; no message text will be loaded for a multi-line
message, but the old text is remembered and if the new command does
not contain a message or a pointer to a message file, the old text
will be re-used.  (Note: the subject line is considered part of the
text, and the state of the /SUBJECT switch may not be changed if the
old text is re-used in this way.)

The second mode of repeating a command is used if the destination list
was given on more than one line or from a non-display.  In this case,
the command and destination list are typed and you are asked if you want
to keep the old destinations.  Whether you answer yes or no, the command
name and global switches are loaded into your line editor (displays only)
and new destinations can be added on the command line.  Finally, if no
message text appears in the re-edited command, the old message is used
as in the first mode.  (Note: in this mode, only valid destinations are
remembered from the old destination list; in the first mode what is
remembered is the actual string of characters you typed.)

If the old text is re-used, in either mode, before sending the message
the MAIL program asks if the user wants to edit the command or the
message text with E.  (Editing with E is allowed whether or not the
user is at a Stanford display, although of course it's easier to do
from a display.  SOS editing is not available because SOS does not
use the same RPG-startup conventions as E.)  In this case, a MAIL.TXT
file is written and E is run as in the <control><meta>E case.
Hand-holding mode

If a SEND, MAIL, or REMIND command is given with no arguments (global
switches may be specified), the MAIL program uses an alternate
syntax, much more verbose but perhaps less confusing to a novice user.
Each required piece of information is prompted for separately:
	"To" destinations
	"CC" destinations
	Date and time if REMIND
	Expiration count if REMIND
	Subject (the /SUBJECT switch will be set if a subject is given)
	Message text

One possibly important difference between this and the normal syntax is
that the subject line is always entered separately from the body of the
message, even if the latter comes from a file.

A minor syntactic difference from the normal format is that in the
time specification for the REMIND command, the format "3:47 PM" with
a space before AM or PM is allowed.

Each prompt may be answered by a line containing just the character "?"
to see a message explaining the format of the required information for
that prompt.

A REENTER command following the use of this format will be treated the
same as one following a multi-line destination list in the normal format.
Interfacing to MAIL from other programs

The MAIL program can be run from another program using the SWAP UUO.
A special facility is provided for providing MAIL with the required
arguments via the ACs which are preserved by the SWAP UUO.  To do
this, start SYS:MAIL.DMP at one LESS than its normal starting address.
The message text (including subject line, if desired) must first be
written in a disk file, or a TMPCOR file if the MAIL program is to
be run in the same job as the swapping program.  MAIL will, if
desired, SWAP back to the originating program (or any other program).
The ACs should be set up this way:

0-5 SWAP UUO arguments for return after MAIL if desired:
	 0 device
	 1 filename
	 2 ext,,mode bits (see UUO manual)
	 3 core,,starting address increment
	 4 file PPN
	 5 login PPN if starting new job
6-16 MAIL arguments:
	 6 destination PPN or file (see below)
	 7 file extension if required
	10 file PPN if required
	11 message text file name
	12 message text file extension
	13 unused
	14 message text file PPN
	15 date and time for REMIND (see below)
	16 flags (see below)
17 is the SWAP AC and is not preserved in return after MAIL.

The flags in 16 are:
	400000,,0	not used
	200000,,0	/-E (if default is /E, otherwise /E)
	100000,,0	/NODIST for ARPAnet mail
	 40000,,0	/LIST
	 20000,,0	/SEND
	 10000,,0	/-HEADER
	  4000,,0	/QUEUE
	  2000,,0	/APPEND
	  1000,,0	/DIST for local mail
	   400,,0	/WHERE
	   200,,0	/SUBJECT
	   100,,0	/MAIL
	    40,,0	/YESMAIL
	    20,,0	/NOMAIL
	    10,,0	/EXPAND
	     4,,0	command is REMIND
	     2,,0	command is MAIL
	     1,,0	command is SEND
	774000		not used
	  2000		read destinations from named file (ACs 6-10)
	  1000		return via SWAP when done
	   400		text input is from TMPCOR file
	   200		delete input text file when done
	   100		send to job (binary number in AC 6)
	    40		send to TTY (SIXBIT name in AC 6)
	    20		destination is * or ARPA (AC 6 ignored)
	    10		mail to explicitly named file (ACs 6-10)
	     4		don't use this bit (/CC)
	     2		/ARPA (2000 bit must also be on)
	     1		if SEND, send to ARPA* (20 bit must also be on)
			if MAIL, delete old contents of file (for PLAN, see below)

Nothing is guaranteed about the results of setting inconsistent or
irrelevant combinations of flags, e.g., /EXPAND for a command other
than REMIND.  Note that the /MAIL switch has two different meanings
for the SEND command and the REMIND command, but is the same bit
in either case.  Bits which are currently unused should be zero.

If the 400 bit in AC 16 is on, the left half of AC 11 is taken as the
TMPCOR file name; the TMPCOR file PPN is the alias PPN of the MAIL job.
The 200 bit in AC 16 will delete either a DSK file or a TMPCOR file.

The usual case is sending a message to a programmer name or PPN.  For
this case, AC 6 should contain the project name (or 0) in the left half
and the programmer name (or 0) in the right half, both in RIGHT-justified
SIXBIT.  Do not use "." for your own PPN (use the PPN explicitly) nor
"*" for wildcard (use 0,,'PRG' for "PRG"; 'PRJ',,0 for "[PRJ,*]";
20 bit in AC 16 for "*").

Mail can be sent to any file (as in the "#file" destination format)
by setting the 0,,10 bit in AC 16 and specifying the filename in
ACs 6-10.  More than one destination, or a recipient at another ARPA
network host, must be specified by using an indirect file as in the
"@file" destination format; set the 0,,2000 bit in AC 16 and specify
the file with the destination list in ACs 6-10.

Any files used (except the TMPCOR message file) must be on device DSK.
No default extensions will be used; specify the desired extension
explicitly.  (The right half of an extension word must be 0.)  A zero
PPN uses the job's alias PPN as usual.

Exactly one of the 7,,0 bits should be on in AC 16 to specify the
command to be carried out.  The effect of the PLAN command is
achieved by specifying a MAIL command with the delete-old-text bit
and explicit file destination (2,,11 in AC 16) and <prg>.PLN[2,2] as
the destination filename.

The date and time in AC 15 is in the format:
	BYTE (4)MONTH(5)DAY(6)YEAR(3)DAY-OF-WEEK(6)HRS,MINS,FLAGS

The flags are used for special formats:
	0,,1	absolute date, DAYCNT in left half
	0,,2	date is tomorrow (lh is zero)
	0,,4	every day reminder (lh is zero)

Otherwise, zero in the left half means today's date, a nonzero
number in the 7,,0 bits is an every-week reminder (1=Wed, 7=Tues),
and anything else is an every-month or every-year reminder with
at least one of the month and year fields zero.  Month 1 is January,
day 1 is the first of the month, and year 1 is 1965.  The HRS field
is hours past midnight (0-23) and the MINS field minutes past the
hour (0-59).  An absolute date (no wild fields) must be in DAYCNT form.

Another facility is also provided for queuing MAIL requests when
the SWAP technique is inappropriate, for example because another
job slot might not be available and your program must keep itself
going rather than be swapped back in later.  This facility was
designed for the FTP server but can be used by other programs.
Write a file with any name and with extension .FTP on [RMD,SYS]
containing, in text form, a MAIL command and destination list
on the first page, and the message text on the second page.  (This
is the format of the MAIL.TXT file used for editing messages with E.)
When the remind phantom is next run, it will try to start a MAIL job
which will execute the command and delete the file.
Summary of major differences from the old MAIL program

1.  Mail can be sent to E-format files.  The actual message transfer
is faster than before because it is done in dump read-alter mode.

2.  The switches are more than one letter and can be applied to
single destinations as well as globally.

3.  More attempt is made to recover gracefully from error conditions.

4.  More than one line of destinations may be typed at the terminal.
Distribution list files can be nested.  The REENTER facility allows
editing of multi-line destination lists and of the message text, and
can be used even before the message has been completely typed.

5.  Hand-holding mode has been added for beginning users and TENEX fans.

6.  The subject line is now included in the header line for local mail
so it can be found easily by directory search in E.

7.  The old MAIL/A feature to add to an existing message has been
eliminated.  This is easily done with RCV or E.  Note that there
is a new /APPEND switch with a different meaning.

8.  The "home terminal" feature for SEND has not been implemented.
It is very time-consuming even when not used and isn't commonly used.

9.  A space is not inserted at the beginning of each line of the
message text, but a space is inserted at the beginning of any line
which would otherwise begin with the "∂" character.